include/FLAC/format.h Source File

00001 /* libFLAC - Free Lossless Audio Codec library
00002  * Copyright (C) 2000,2001,2002,2003  Josh Coalson
00003  *
00004  * This library is free software; you can redistribute it and/or
00005  * modify it under the terms of the GNU Library General Public
00006  * License as published by the Free Software Foundation; either
00007  * version 2 of the License, or (at your option) any later version.
00008  *
00009  * This library is distributed in the hope that it will be useful,
00010  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00011  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00012  * Library General Public License for more details.
00013  *
00014  * You should have received a copy of the GNU Library General Public
00015  * License along with this library; if not, write to the
00016  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
00017  * Boston, MA  02111-1307, USA.
00018  */
00019 
00020 #ifndef FLAC__FORMAT_H
00021 #define FLAC__FORMAT_H
00022 
00023 #include "export.h"
00024 #include "ordinals.h"
00025 
00026 #ifdef __cplusplus
00027 extern "C" {
00028 #endif
00029 
00074 /*
00075     Most of the values described in this file are defined by the FLAC
00076     format specification.  There is nothing to tune here.
00077 */
00078 
00080 #define FLAC__MIN_BLOCK_SIZE (16u)
00081 
00083 #define FLAC__MAX_BLOCK_SIZE (65535u)
00084 
00086 #define FLAC__MAX_CHANNELS (8u)
00087 
00089 #define FLAC__MIN_BITS_PER_SAMPLE (4u)
00090 
00092 #define FLAC__MAX_BITS_PER_SAMPLE (32u)
00093 
00102 #define FLAC__REFERENCE_CODEC_MAX_BITS_PER_SAMPLE (24u)
00103 
00108 #define FLAC__MAX_SAMPLE_RATE (655350u)
00109 
00111 #define FLAC__MAX_LPC_ORDER (32u)
00112 
00116 #define FLAC__MIN_QLP_COEFF_PRECISION (5u)
00117 
00121 #define FLAC__MAX_QLP_COEFF_PRECISION (15u)
00122 
00124 #define FLAC__MAX_FIXED_ORDER (4u)
00125 
00127 #define FLAC__MAX_RICE_PARTITION_ORDER (15u)
00128 
00130 #define FLAC__SUBSET_MAX_RICE_PARTITION_ORDER (8u)
00131 
00138 extern FLAC_API const char *FLAC__VERSION_STRING;
00139 
00144 extern FLAC_API const char *FLAC__VENDOR_STRING;
00145 
00147 extern FLAC_API const FLAC__byte FLAC__STREAM_SYNC_STRING[4]; /* = "fLaC" */
00148 
00152 extern FLAC_API const unsigned FLAC__STREAM_SYNC; /* = 0x664C6143 */
00153 
00155 extern FLAC_API const unsigned FLAC__STREAM_SYNC_LEN; /* = 32 bits */
00156 
00158 #define FLAC__STREAM_SYNC_LENGTH (4u)
00159 
00160 
00161 /*****************************************************************************
00162  *
00163  * Subframe structures
00164  *
00165  *****************************************************************************/
00166 
00167 /*****************************************************************************/
00168 
00170 typedef enum {
00171     FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE = 0
00174 } FLAC__EntropyCodingMethodType;
00175 
00181 extern FLAC_API const char * const FLAC__EntropyCodingMethodTypeString[];
00182 
00183 
00186 typedef struct {
00187 
00188     unsigned *parameters;
00191     unsigned *raw_bits;
00194     unsigned capacity_by_order;
00199 } FLAC__EntropyCodingMethod_PartitionedRiceContents;
00200 
00203 typedef struct {
00204 
00205     unsigned order;
00208     const FLAC__EntropyCodingMethod_PartitionedRiceContents *contents;
00211 } FLAC__EntropyCodingMethod_PartitionedRice;
00212 
00213 extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ORDER_LEN; 
00214 extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN; 
00215 extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_RAW_LEN; 
00217 extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ESCAPE_PARAMETER;
00222 typedef struct {
00223     FLAC__EntropyCodingMethodType type;
00224     union {
00225         FLAC__EntropyCodingMethod_PartitionedRice partitioned_rice;
00226     } data;
00227 } FLAC__EntropyCodingMethod;
00228 
00229 extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_TYPE_LEN; 
00231 /*****************************************************************************/
00232 
00234 typedef enum {
00235     FLAC__SUBFRAME_TYPE_CONSTANT = 0, 
00236     FLAC__SUBFRAME_TYPE_VERBATIM = 1, 
00237     FLAC__SUBFRAME_TYPE_FIXED = 2, 
00238     FLAC__SUBFRAME_TYPE_LPC = 3 
00239 } FLAC__SubframeType;
00240 
00246 extern FLAC_API const char * const FLAC__SubframeTypeString[];
00247 
00248 
00251 typedef struct {
00252     FLAC__int32 value; 
00253 } FLAC__Subframe_Constant;
00254 
00255 
00258 typedef struct {
00259     const FLAC__int32 *data; 
00260 } FLAC__Subframe_Verbatim;
00261 
00262 
00265 typedef struct {
00266     FLAC__EntropyCodingMethod entropy_coding_method;
00269     unsigned order;
00272     FLAC__int32 warmup[FLAC__MAX_FIXED_ORDER];
00275     const FLAC__int32 *residual;
00277 } FLAC__Subframe_Fixed;
00278 
00279 
00282 typedef struct {
00283     FLAC__EntropyCodingMethod entropy_coding_method;
00286     unsigned order;
00289     unsigned qlp_coeff_precision;
00292     int quantization_level;
00295     FLAC__int32 qlp_coeff[FLAC__MAX_LPC_ORDER];
00298     FLAC__int32 warmup[FLAC__MAX_LPC_ORDER];
00301     const FLAC__int32 *residual;
00303 } FLAC__Subframe_LPC;
00304 
00305 extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_COEFF_PRECISION_LEN; 
00306 extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_SHIFT_LEN; 
00311 typedef struct {
00312     FLAC__SubframeType type;
00313     union {
00314         FLAC__Subframe_Constant constant;
00315         FLAC__Subframe_Fixed fixed;
00316         FLAC__Subframe_LPC lpc;
00317         FLAC__Subframe_Verbatim verbatim;
00318     } data;
00319     unsigned wasted_bits;
00320 } FLAC__Subframe;
00321 
00322 extern FLAC_API const unsigned FLAC__SUBFRAME_ZERO_PAD_LEN; 
00323 extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LEN; 
00324 extern FLAC_API const unsigned FLAC__SUBFRAME_WASTED_BITS_FLAG_LEN; 
00326 extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_CONSTANT_BYTE_ALIGNED_MASK; /* = 0x00 */
00327 extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_VERBATIM_BYTE_ALIGNED_MASK; /* = 0x02 */
00328 extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_FIXED_BYTE_ALIGNED_MASK; /* = 0x10 */
00329 extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LPC_BYTE_ALIGNED_MASK; /* = 0x40 */
00330 
00331 /*****************************************************************************/
00332 
00333 
00334 /*****************************************************************************
00335  *
00336  * Frame structures
00337  *
00338  *****************************************************************************/
00339 
00341 typedef enum {
00342     FLAC__CHANNEL_ASSIGNMENT_INDEPENDENT = 0, 
00343     FLAC__CHANNEL_ASSIGNMENT_LEFT_SIDE = 1, 
00344     FLAC__CHANNEL_ASSIGNMENT_RIGHT_SIDE = 2, 
00345     FLAC__CHANNEL_ASSIGNMENT_MID_SIDE = 3 
00346 } FLAC__ChannelAssignment;
00347 
00353 extern FLAC_API const char * const FLAC__ChannelAssignmentString[];
00354 
00356 typedef enum {
00357     FLAC__FRAME_NUMBER_TYPE_FRAME_NUMBER, 
00358     FLAC__FRAME_NUMBER_TYPE_SAMPLE_NUMBER 
00359 } FLAC__FrameNumberType;
00360 
00366 extern FLAC_API const char * const FLAC__FrameNumberTypeString[];
00367 
00368 
00371 typedef struct {
00372     unsigned blocksize;
00375     unsigned sample_rate;
00378     unsigned channels;
00381     FLAC__ChannelAssignment channel_assignment;
00384     unsigned bits_per_sample;
00387     FLAC__FrameNumberType number_type;
00390     union {
00391         FLAC__uint32 frame_number;
00392         FLAC__uint64 sample_number;
00393     } number;
00397     FLAC__uint8 crc;
00402 } FLAC__FrameHeader;
00403 
00404 extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC; 
00405 extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC_LEN; 
00406 extern FLAC_API const unsigned FLAC__FRAME_HEADER_RESERVED_LEN; 
00407 extern FLAC_API const unsigned FLAC__FRAME_HEADER_BLOCK_SIZE_LEN; 
00408 extern FLAC_API const unsigned FLAC__FRAME_HEADER_SAMPLE_RATE_LEN; 
00409 extern FLAC_API const unsigned FLAC__FRAME_HEADER_CHANNEL_ASSIGNMENT_LEN; 
00410 extern FLAC_API const unsigned FLAC__FRAME_HEADER_BITS_PER_SAMPLE_LEN; 
00411 extern FLAC_API const unsigned FLAC__FRAME_HEADER_ZERO_PAD_LEN; 
00412 extern FLAC_API const unsigned FLAC__FRAME_HEADER_CRC_LEN; 
00417 typedef struct {
00418     FLAC__uint16 crc;
00423 } FLAC__FrameFooter;
00424 
00425 extern FLAC_API const unsigned FLAC__FRAME_FOOTER_CRC_LEN; 
00430 typedef struct {
00431     FLAC__FrameHeader header;
00432     FLAC__Subframe subframes[FLAC__MAX_CHANNELS];
00433     FLAC__FrameFooter footer;
00434 } FLAC__Frame;
00435 
00436 /*****************************************************************************/
00437 
00438 
00439 /*****************************************************************************
00440  *
00441  * Meta-data structures
00442  *
00443  *****************************************************************************/
00444 
00446 typedef enum {
00447 
00448     FLAC__METADATA_TYPE_STREAMINFO = 0,
00451     FLAC__METADATA_TYPE_PADDING = 1,
00454     FLAC__METADATA_TYPE_APPLICATION = 2,
00457     FLAC__METADATA_TYPE_SEEKTABLE = 3,
00460     FLAC__METADATA_TYPE_VORBIS_COMMENT = 4,
00463     FLAC__METADATA_TYPE_CUESHEET = 5,
00466     FLAC__METADATA_TYPE_UNDEFINED = 6
00469 } FLAC__MetadataType;
00470 
00476 extern FLAC_API const char * const FLAC__MetadataTypeString[];
00477 
00478 
00481 typedef struct {
00482     unsigned min_blocksize, max_blocksize;
00483     unsigned min_framesize, max_framesize;
00484     unsigned sample_rate;
00485     unsigned channels;
00486     unsigned bits_per_sample;
00487     FLAC__uint64 total_samples;
00488     FLAC__byte md5sum[16];
00489 } FLAC__StreamMetadata_StreamInfo;
00490 
00491 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_BLOCK_SIZE_LEN; 
00492 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_BLOCK_SIZE_LEN; 
00493 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_FRAME_SIZE_LEN; 
00494 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_FRAME_SIZE_LEN; 
00495 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_SAMPLE_RATE_LEN; 
00496 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_CHANNELS_LEN; 
00497 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_BITS_PER_SAMPLE_LEN; 
00498 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_TOTAL_SAMPLES_LEN; 
00499 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MD5SUM_LEN; 
00502 #define FLAC__STREAM_METADATA_STREAMINFO_LENGTH (34u)
00503 
00506 typedef struct {
00507     int dummy;
00512 } FLAC__StreamMetadata_Padding;
00513 
00514 
00517 typedef struct {
00518     FLAC__byte id[4];
00519     FLAC__byte *data;
00520 } FLAC__StreamMetadata_Application;
00521 
00522 extern FLAC_API const unsigned FLAC__STREAM_METADATA_APPLICATION_ID_LEN; 
00526 typedef struct {
00527     FLAC__uint64 sample_number;
00530     FLAC__uint64 stream_offset;
00534     unsigned frame_samples;
00536 } FLAC__StreamMetadata_SeekPoint;
00537 
00538 extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_SAMPLE_NUMBER_LEN; 
00539 extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_STREAM_OFFSET_LEN; 
00540 extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_FRAME_SAMPLES_LEN; 
00543 #define FLAC__STREAM_METADATA_SEEKPOINT_LENGTH (18u)
00544 
00549 extern FLAC_API const FLAC__uint64 FLAC__STREAM_METADATA_SEEKPOINT_PLACEHOLDER;
00550 
00551 
00564 typedef struct {
00565     unsigned num_points;
00566     FLAC__StreamMetadata_SeekPoint *points;
00567 } FLAC__StreamMetadata_SeekTable;
00568 
00569 
00572 typedef struct {
00573     FLAC__uint32 length;
00574     FLAC__byte *entry;
00575 } FLAC__StreamMetadata_VorbisComment_Entry;
00576 
00577 extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_ENTRY_LENGTH_LEN; 
00582 typedef struct {
00583     FLAC__StreamMetadata_VorbisComment_Entry vendor_string;
00584     FLAC__uint32 num_comments;
00585     FLAC__StreamMetadata_VorbisComment_Entry *comments;
00586 } FLAC__StreamMetadata_VorbisComment;
00587 
00588 extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_NUM_COMMENTS_LEN; 
00595 typedef struct {
00596     FLAC__uint64 offset;
00601     FLAC__byte number;
00603 } FLAC__StreamMetadata_CueSheet_Index;
00604 
00605 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_OFFSET_LEN; 
00606 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_NUMBER_LEN; 
00607 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_RESERVED_LEN; 
00614 typedef struct {
00615     FLAC__uint64 offset;
00618     FLAC__byte number;
00621     char isrc[13];
00624     unsigned type:1;
00627     unsigned pre_emphasis:1;
00630     FLAC__byte num_indices;
00633     FLAC__StreamMetadata_CueSheet_Index *indices;
00636 } FLAC__StreamMetadata_CueSheet_Track;
00637 
00638 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_OFFSET_LEN; 
00639 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUMBER_LEN; 
00640 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_ISRC_LEN; 
00641 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_TYPE_LEN; 
00642 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_PRE_EMPHASIS_LEN; 
00643 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_RESERVED_LEN; 
00644 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUM_INDICES_LEN; 
00651 typedef struct {
00652     char media_catalog_number[129];
00658     FLAC__uint64 lead_in;
00661     FLAC__bool is_cd;
00664     unsigned num_tracks;
00667     FLAC__StreamMetadata_CueSheet_Track *tracks;
00670 } FLAC__StreamMetadata_CueSheet;
00671 
00672 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_MEDIA_CATALOG_NUMBER_LEN; 
00673 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_LEAD_IN_LEN; 
00674 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_IS_CD_LEN; 
00675 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_RESERVED_LEN; 
00676 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_NUM_TRACKS_LEN; 
00683 typedef struct {
00684     FLAC__byte *data;
00685 } FLAC__StreamMetadata_Unknown;
00686 
00687 
00690 typedef struct {
00691     FLAC__MetadataType type;
00696     FLAC__bool is_last;
00699     unsigned length;
00702     union {
00703         FLAC__StreamMetadata_StreamInfo stream_info;
00704         FLAC__StreamMetadata_Padding padding;
00705         FLAC__StreamMetadata_Application application;
00706         FLAC__StreamMetadata_SeekTable seek_table;
00707         FLAC__StreamMetadata_VorbisComment vorbis_comment;
00708         FLAC__StreamMetadata_CueSheet cue_sheet;
00709         FLAC__StreamMetadata_Unknown unknown;
00710     } data;
00713 } FLAC__StreamMetadata;
00714 
00715 extern FLAC_API const unsigned FLAC__STREAM_METADATA_IS_LAST_LEN; 
00716 extern FLAC_API const unsigned FLAC__STREAM_METADATA_TYPE_LEN; 
00717 extern FLAC_API const unsigned FLAC__STREAM_METADATA_LENGTH_LEN; 
00720 #define FLAC__STREAM_METADATA_HEADER_LENGTH (4u)
00721 
00722 /*****************************************************************************/
00723 
00724 
00725 /*****************************************************************************
00726  *
00727  * Utility functions
00728  *
00729  *****************************************************************************/
00730 
00731 /* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
00740 FLAC_API FLAC__bool FLAC__format_sample_rate_is_valid(unsigned sample_rate);
00741 
00742 /* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
00753 FLAC_API FLAC__bool FLAC__format_seektable_is_legal(const FLAC__StreamMetadata_SeekTable *seek_table);
00754 
00755 /* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
00768 FLAC_API unsigned FLAC__format_seektable_sort(FLAC__StreamMetadata_SeekTable *seek_table);
00769 
00770 /* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
00789 FLAC_API FLAC__bool FLAC__format_cuesheet_is_legal(const FLAC__StreamMetadata_CueSheet *cue_sheet, FLAC__bool check_cd_da_subset, const char **violation);
00790 
00791 /* \} */
00792 
00793 #ifdef __cplusplus
00794 }
00795 #endif
00796 
00797 #endif